package reesoft.common.dao;

import java.util.Collection;
import java.util.List;
import java.util.Map;

/**
 * 数据仓库接口类，声明通用的数据存取接口，减少重复的函数声明
 * 具体实现 SQL 语句定义在 Mapper 配置文件中，配置文件中如果没有与接口函数同名的定义，调用接口函数将抛出异常
 *
 * 使用示例：定义存取 User 实体的派生类（空类）
 * public interface UserRepository extends BaseRepository<User> { }
 *
 * 派生类中可自定义新的接口函数，在 Mapper 配置文件中增加同名定义即可
 *
 * @param <DataType> 存取的实体数据类型
 * Created by reesoft on 2017-08-23
 */
public interface BaseRepository<DataType>
{
    /**
     * 添加数据记录入库
     *
     * 具体的 SQL 定义见 mapper 文件中的定义：例如 UserMapper.xml：id="add"
     *
     * @param data 要添加的数据对象
     * @return 操作结果代码，0 失败，1 成功
     */
    int add(DataType data);

    /**
     * 添加数据记录入库，忽略值为 NULL 的字段
     *
     * 具体的 SQL 定义见 mapper 文件中的定义：例如 UserMapper.xml：id="addSelective"
     *
     * @param data 要添加的数据对象
     * @return 操作结果代码，0 失败，1 成功
     */
    int addSelective(DataType data);

    /**
     * 删除数据记录
     *
     * 具体的 SQL 定义见 mapper 文件中的定义：例如 UserMapper.xml：id="delete"
     *
     * @param data 包含删除条件的数据对象
     * @return 操作结果代码，0 失败，非 0 成功
     */
    int delete(DataType data);

    /**
     * 删除数据记录
     *
     * 具体的 SQL 定义见 mapper 文件中的定义：例如 UserMapper.xml：id="deleteById"
     *
     * @param id 要删除的记录主键值
     * @return 操作结果代码，0 失败，1 成功
     */
    int deleteById(long id);

    /**
     * 批量删除数据记录
     *
     * 具体的 SQL 定义见 mapper 文件中的定义：例如 UserMapper.xml：id="deleteBatch"
     *
     * @param ids 要删除的记录主键值集合
     * @return 操作结果代码，0 失败，非 0 成功
     */
    int deleteBatch(Collection<Long> ids);

    /**
     * 更新数据记录
     *
     * 具体的 SQL 定义见 mapper 文件中的定义：例如 UserMapper.xml：id="update"
     *
     * @param data 要更新的数据对象
     * @return 操作结果代码，0 失败，1 成功
     */
    int update(DataType data);

    /**
     * 更新数据记录，忽略值为 NULL 的字段
     *
     * 具体的 SQL 定义见 mapper 文件中的定义：例如 UserMapper.xml：id="updateSelective"
     *
     * @param data 要更新的数据对象
     * @return 操作结果代码，0 失败，1 成功
     */
    int updateSelective(DataType data);

    /**
     * 按照主键查询数据记录，转换成对象输出
     *
     * 具体的 SQL 定义见 mapper 文件中的定义：例如 UserMapper.xml：id="get"
     *
     * @param id 要查询的记录的主键值
     * @return 查询到的记录对象，null 表示查不到记录
     */
    DataType get(long id);

    /**
     * 按条件查询记录
     *
     * 具体的 SQL 定义见 mapper 文件中的定义：例如 UserMapper.xml：id="getList"
     *
     * @param criteria 查询条件
     * @return 查询到的记录集合
     */
    List<DataType> getList(Map<String, Object> criteria);

    /**
     * 按条件查询指定页码的记录
     *
     * 具体的 SQL 定义见 mapper 文件中的定义：例如 UserMapper.xml：id="getListForPage"
     *
     * @param criteria 查询条件
     * @param pageSize 页大小
     * @param page 页码，从 1 开始
     * @return 查询到的记录集合
     */
    List<DataType> getListForPage(Map<String, Object> criteria, int pageSize, int page);

    /**
     * 获取满足查询条件的数据总条数
     *
     * 具体的 SQL 定义见 mapper 文件中的定义：例如 UserMapper.xml：id="getCount"
     *
     * @param criteria 查询条件
     * @return 满足查询条件的数据总条数
     */
    long getCount(Map<String, Object> criteria);
}
